Description

In this example, the TRIDENT document signing API is used to sign a batch of three PDF documents. I.e., the user only has to perform one signature process to sign three documents. The PDF documents have the same content, and they are requested to have the same appearance.

This operation is requested by a document signature portal (doc_sign) on behalf of a user (john.doe) who logged in to the portal after authenticating in the TRIDENT by password. Signing document batches entails the following steps:

1. Obtaining the token for accessing the signature operations

2. Creating the documents

3. Creating the signature process

4. Executing the signature process

5. Obtaining information on and the result of the signed documents

6. Obtaining the signed documents

Lastly, after the signed documents are obtained, the documents are deleted and the signature process is deleted from the server.

The portal was registered in the TRIDENT (txeidas.safelayer.com) as an OAuth 2.0 client application, which means it has an identifier (docsign) and shares a secret with the platform (demodemo). Furthermore, the portal was associated to two authorization servers: one (main) for obtaining the access tokens for accessing the identity data of users; and the other (esignsp) for obtaining the access tokens for performing the signature operations on the documents.

During the signature process, the TRIDENT obtains authorization implicitly from the user on two occasions:

• The first time so that the signature services provider can obtain the user's signing identities: the reauthentication associated to this authorization does not require the user's intervention as it is performed with the same authentication flow used to log in to the portal and this flow establishes SSO for the password factor.

• The second time so that the signature services provider can generate the signature on the batch of documents using one of the user's signature identities: the reauthentication associated to this authorization only requires user intervention if the signatures are to be generated on a server because, in such a case, the reauthentication is performed with a flow that, in addition to the password (which is not prompted for again because it has factor SSO), requires an OTP (which is always prompted for because it has no factor SSO). Furthermore, the associated reauthentication does not require the user's intervention if the signature must be generated with a mobile device as in this case the reauthentication is performed with the same authentication flow used to log in to the portal and this flow establishes SSO for the password factor.

The portal is indifferent to which signing identity is used for signing. The user chooses this identity from the signing identities presented to them by the TRIDENT after obtaining the corresponding authorization.

Obtaining the Token for Accessing the Signature Operations

Firstly, the document signature portal sends the following message to the TRIDENT to obtain the access token for accessing the PDF document signing operations (see the Obtain a Token operation):

Note that the portal must use its identifier and the secret it shares with the TRIDENT to authenticate using the HTTP basic authentication scheme (RFC 2617). Also note that the portal specifies that its authentication also proves having the right to obtain the access token requested (grant_type=client_credentials).

The access token is obtained in the following HTTP response:

Creating the Documents

Second, the signature portal lets the user choose the documents to be signed. Either by letting them upload the documents to the portal or select documents that the portal already has access to. Next, the portal creates each of the Document resources of the API by sending the PDF document. The portal must send a request for the Create a Document Signature Process operation for each of the three documents.

To provide the names of the documents to be signed so the names can later be displayed in the graphical interface for accepting the documents, of the three variants admitted by the request of the Create a document and signature definitions operation, the one for sending a document and its signature definitions in a multipart entity must be used with the part of the signature definitions left empty.

The portal demonstrates its authorization for requesting document signing by including the access token (403e...e7b3) in the Authorization header. Note also that the previous message corresponds to the request for creating a documentName document.

For the sake of readability, {pdfToBeSigned} replaces the binary content of the PDF document, which is what the signature portal would send exclusively to the server in the message. The part of the signature definitions of the document (the "signers" part) is sent empty as all the documents in the batch have the same signature definition, which is specified subsequently.

In response to each request, the server responds with a message like the following:

Creating the Signature Process

The portal requests the creation of the PDF document batch signature process by sending the following message to the TRIDENT signature services provider (see the Create a Document Signature Process operation).

The portal demonstrates its authorization for requesting the signing of the document by including the access token (403e...e7b3) in the Authorization header. The request omits the multipart/form-data entity that supports this operation because it only specifies the "process" part that contains a JSON object with the data required for creating the signature process.

With regard to the characteristics of the process, the request specifies:

• The type (process_type=urn:safelayer:eidas:processes:document:sign:esigp) for requesting signing with signing identities protected by the TRIDENT.

• The "sign" label to specify the type of signing identity that the user can select.

• The finished_callback_url property to specify the URL for notifying the finalizing of the signature process (returnurl=https://docsign.safelayer.com/signedPdf/callback).

• The language preference of the user's GUI ("en_US").

• The documents created on the server that will be signed (documents), specifying the identifiers obtained in the previous step.

In the above message, you can also see the following with regard to the definition of the signatures:

• A PAdES-BES (signer.parameters.type = "pades-bes") signature is to be performed, and the SHA-256 hash algorithm (signer.parameters.default_digest_algorithm = "sha256") is to be used for calculating the digital signature.

• The signature is to have an appearance (parameters.signature_field.appearance) to be located on the last page of the document (signer.parameters.signature_field.location.page.number = "last").

• The signature appearance comprises text, namely the distinguished name of the signer and the date and time the signature was made (signer.parameters.signature_field.appearance.signature_details.details[0].type = "subject", signer.parameters.signature_field.appearance.signature_details.details[1].type = "location" and signer.parameters.signature_field.appearance.signature_details.details[2].type = "date").

• Madrid, Spain is indicated as the place where the signature was generated (signer.parameters.location = "Madrid, Spain").

If the request is successfully processed, the TRIDENT creates the signature process for the document and responds to the document signature portal with the following HTTP message.

In the above example, you can see that the TRIDENT communicates with the signature portal that successfully created the signature process and that must redirect the user's browser to https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/ui?signerProcessId=sp_c4eed0a1f478f72454803695d53c4c5 (tasks.pending.url) for this process to continue. TRIDENT also sends to the signature portal the information for accessing each signed document when the execution of the process finalizes. For example, it must access https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/documents/h5ee423kj498237842/content to obtain the first document.

Executing the Signature Process

Next, the portal orders that the signature process be executed via the browser. Specifically, the portal sends the following redirect message to the browser (see the Execute a Document Signature Process operation):

To which the browser reacts by sending the following HTTP request to the TRIDENT:

To attend to this request, the TRIDENT's electronic signature services provider, having previously obtained the corresponding authorization from the user, accesses the user's signing identities and, if there are more than one, prompts the user to select the one they want to sign the document with. Next, the user can browse the details of the documents that the application wants to be signed. The user must acknowledge they have read the documents before they can confirm their signature. To sign, authorization is again obtained from the user, and the signature provider is requested to generate the signature on the batch of documents with the signing identity selected. Lastly, after receiving the signatures on the documents from the signature provider, the signature services provider inserts them in the corresponding PDF document and notifies the signature portal that the process has finished by sending the following redirect response to the browser (which sends the browser to the URL specified in the signer.finish_callback_url property of the request received to create the signature process):

To which the browser reacts by sending the following HTTP request to the document signature portal:

In this redirect, the signature portal receives the identifier of the signature process for the document to facilitate the following steps. It also receives the overall result from the signature process executed on the document batch, which allows deciding what actions are to be taken in the following steps:

• finished: All the documents were successfully signed. The portal can obtain the signed documents.

• failed: The process ended with an error and none of the documents were signed correctly. The portal deletes the documents and deletes the signature process from the server, or it obtains the information on and results for all the documents in the batch to notify the user of the reason for the failure in each case.

• failed_documents: Some but not all of the documents were signed. The portal obtains the information on and results for all the documents in the batch to notify the user of the reason for the failure in each case.
  

• canceled: The user canceled the process and none of the documents were signed correctly. The portal deletes the documents and deletes the signature process from the server.

Obtaining Information on and the Result of the Signed Documents

The signature portal, once it recovers control of the interaction with the user, can carry out this step to recover the result of the signing of each document in the batch and/or to obtain how each of the signed documents must be accessed.

The following message is sent to the TRIDENT signature services provider:

Note that the portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header. The URL of the server also contains the identifier of the signature process obtained in the previous step following the execution of the signature process.

In response, the portal receives the information on all the documents in the batch in a message like the following:

The information on each of the documents in the batch is returned with the content property that allows accessing the content so the portal can obtain the signed documents. The result property is also returned. This property tells the portal the result of the execution of the signature process on each document. In this case, as the signature process ended with the finished result, the same result was returned for all three documents. However, if the result had been different, this property could include values such as the following:

When signature execution on a document returns the failed result, the result.details.message property notifies the portal of the reason for the error.

Obtaining the Signed Documents

When the document signature portal has the result of the signing process on the three documents that the user requested to sign, the portal can obtain each signed document by sending the following message to the signature services provider of the TRIDENT to obtain the signed PDF documents (see the Obtain a Document operation):

The portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header. The portal could have obtained the URL of the document requested in the steps for creating the signature process and for obtaining information on and the result of the signed documents.

Lastly, the portal receives each signed document in the following HTTP response message (for the sake of readability, {pdfSigned} replaces the binary content of the signed PDF).

Deleting the Documents

When the portal has obtained the PDF documents signed in the signature process, it must notify the TRIDENT signature services provider that the documents are no longer required on the server. To do this, a message such as the following must be sent for each document.

The portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header. The portal could have obtained the URL of the document requested in the steps for creating the signature process and for obtaining information on and the result of the signed documents.

Deleting the Document Signature Process

After obtaining the signed PDF documents, the document signature portal sends the following message to the TRIDENT's signature services provider to delete the document signature process used (see the Delete a Document Signature Process operation):

TRIDENT deletes the document signature process and responds with the following message: